[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: nerdeveloper
Once this PR has been reviewed and has the lgtm label, please assign camilamacedo86 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Hi @nerdeveloper. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Hi @camilamacedo86,

Thank you for the review feedback! I've updated the documentation to address your comments:

✅ Changed title to "Creating Custom Markers" (broader scope, not just for unsupported extensions)
✅ Simplified to only ONE example (Rust) instead of multiple examples
✅ Removed "Best Practices" section (subjective term)
✅ Removed "Conclusion" section (to match other docs)
✅ Made the documentation more concise and maintainable

Regarding testing: I performed minimal testing of the marker generation logic by creating a standalone Go program that tests the core marker creation code. The test confirms:

• The code compiles without errors
• Markers are generated with correct comment syntax for different file types (e.g., // +rust:scaffold:imports for Rust, # +python:scaffold:functions for Python)
• The marker format is correct

However, I have NOT tested the complete integration with external plugins end-to-end (the full example with templates and plugin integration).

Question: What would you prefer for this documentation?

1. Keep the current example as a pattern/reference (with a note that it's not fully integration-tested)
2. Simplify further to only show the minimal testable code (just the marker creation)
3. Add a working example to an external test repository and link to it

Please let me know your preference, and I'll update accordingly!

How to Test This Implementation

@camilamacedo86 Here are step-by-step instructions to test the custom marker implementation:

Quick Test

1. Test the core marker functionality:

# Create a test file in any directory
cat > test_markers.go << 'EOF'
package main

import (
	"fmt"
	"path/filepath"
	"strings"
)

const RustPluginPrefix = "+rust:scaffold:"

type RustMarker struct {
	prefix  string
	comment string
	value   string
}

func NewRustMarker(path string, value string) (RustMarker, error) {
	ext := filepath.Ext(path)
	if ext != ".rs" {
		return RustMarker{}, fmt.Errorf("expected .rs file, got %s", ext)
	}
	return RustMarker{
		prefix:  formatPrefix(RustPluginPrefix),
		comment: "//",
		value:   value,
	}, nil
}

func (m RustMarker) String() string {
	return m.comment + " " + m.prefix + m.value
}

func formatPrefix(prefix string) string {
	trimmed := strings.TrimSpace(prefix)
	var builder strings.Builder
	if !strings.HasPrefix(trimmed, "+") {
		builder.WriteString("+")
	}
	builder.WriteString(trimmed)
	if !strings.HasSuffix(trimmed, ":") {
		builder.WriteString(":")
	}
	return builder.String()
}

func main() {
	fmt.Println("Testing marker creation...")
	marker, err := NewRustMarker("src/main.rs", "imports")
	if err != nil {
		fmt.Printf("Error: %v", err)
		return
	}
	fmt.Printf("Generated marker: %s", marker.String())
	
	// Test error case
	_, err = NewRustMarker("main.go", "imports")
	if err != nil {
		fmt.Printf("\nCorrect error for Go file: %v", err)
	}
}
EOF

# Run the test
go run test_markers.go

Expected output:

Testing marker creation...
Generated marker: // +rust:scaffold:imports
Correct error for Go file: expected .rs file, got .go

Verify External Plugin Imports

2. Test that external plugin types are accessible:

cat > test_external.go << 'EOF'
package main

import (
	"fmt"
	"sigs.k8s.io/kubebuilder/v4/pkg/plugin/external"
)

func main() {
	var req external.PluginRequest
	var resp external.PluginResponse
	fmt.Printf("PluginRequest available: %T\n", req)
	fmt.Printf("PluginResponse available: %T\n", resp)
	fmt.Println("External plugin imports working!")
}
EOF

go run test_external.go

Expected output:

PluginRequest available: external.PluginRequest
PluginResponse available: external.PluginResponse
External plugin imports working!

Clean Up

rm test_markers.go test_external.go

when all is good, i wil squash all of them into one commit

@nerdeveloper

Could you please:

• Run make remove-spaces to fix the check.
• And squash the commits I think it is good to get merged

Thank you a lot for your contribution 🎉

@camilamacedo86 do you want me to also implement copilot suggestions on this pr.

Hi @nerdeveloper

For we get this merged we need to:

• Run make remove-spaces
• Squash the commits
• And the reviews that make sense from copilot; can you please address?

Keywords which can automatically close issues and at(@) or hashtag(#) mentions are not allowed in commit messages.

The list of commits with invalid commit messages:

• c51a0a6 📖 Add docs: Creating custom markers for unsupported file extensions

@camilamacedo86 All requested changes have been completed:

✅ Trailing spaces removed - Ran make remove-spaces successfully
✅ Commits squashed - All 5 commits consolidated into 1 meaningful commit
✅ Copilot suggestions addressed:

• Added note about formatPrefix being adapted from Kubebuilder's internal implementation
• Added proper error handling for json.Marshal calls (2 instances)
• Expanded universe comment to explain its purpose and usage